home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Deutsche Edition 1
/
Deutsche Edition 1.iso
/
amok
/
amok_lha
/
amok22.lha
/
Lists
/
Lists.dok
< prev
next >
Wrap
Text File
|
1993-08-15
|
7KB
|
212 lines
======================================================================
Dokumentation zu "Lists" Version 2.0
Autor: Nicolas Benezan, Postwiesenstr. 2, D7000 Stuttgart 60
======================================================================
Kopierrecht
Das komplette Packet (Quelltext, Dokumentation und Objectcode) ist
Public Domain Software. Es darf beliebig kopiert und verbreitet werden
solange...
* mein Name und dieser Kopierrechtshinweis erhalten bleiben,
* die Vollständigkeit des ganzen Packets gewährleistet ist, und
* mit dem Vertrieb dieser Software kein Gewinn erwirtschaftet wird.
Die Kommerzielle Nutzung ohne meine ausdrückliche schriftliche
Genehmigung ist untersagt.
Ferner ist allen Personen, die in irgend einer Weise etwas mit "Data
Becker" zu tun haben, insbesondere für "Data Becker" arbeiten oder
deren Produkte verkaufen, jegliche Verwendung dieser Software verboten.
Verbesserungsvorschläge sind stets willkommen. Falls Sie Veränderungen
am Programm vornehmen, dokumentieren Sie diese bitte gut verständlich.
Es würde mich freuen, wenn Sie mich über größere Veränderungen in
Kenntnis setzen würden.
(c) 1988 by Nicolas Benezan.
Übersicht
* Umfang des Packets
* Einleitung
* Beschreibung der Prozeduren
* Weitere generische Datentypen
Umfang des Packet
Das komplette Packet "Lists" beinhaltet folgendes:
* Lists.dok Diese Dokumentation
* Lists.doc Englische Dokumentation
* Lists.def Definitionsmodul
* Lists.mod Implementationsmodul
* Lists.sym Symboldatei (compiliertes Definitionsodul)
* Lists.obj Objektcode (compiliertes Implementationsmodul)
* TestLists.mod Testmodul für Lists
* TestLists.obj Objektcode
* TestLists Ausführbares Testmodul
Einleitung
Falls Sie mit dem Prinzip der generischen Datentypen noch nicht vertraut
sind, empfielt es sich, die Dokumentationen von [1]-[4] durchzulesen.
Dieses Modul stellt den generischen Datentyp "List" zur Verfügung. Es ist
eine komplett neue Version des auf Amok#7 befindlichen List-Moduls und
bietet wesentlich umfangreichere Operationen.
Da die Listen jetzt vorwärts und rückwärts verzeigert sind, ist es nun
möglich, gezielt auf bestimmte Einträge absolut oder relativ zu
positionieren, anstatt die Liste immer nur von Anfang an durchzugehen.
Durch den exportierten Typ EntryPtr kann man sich auch bestimmte Stellen in
der Liste "merken" und zwischen diesen hin und her springen.
Die Operationen ReadEntry, AppendEntry, InsertEntry und ReplaceEntry
existieren jeweils in zwei Versionen: eine mit Kopieren der Daten und eine,
die nur mit Zeigern arbeitet. Es ist so zum Beispiel möglich, eine Liste
schnell nach einem Datenfeld zu durchsuchen, ohne die gesammten Daten in
lokale Variablen kopieren zu müssen. (Allerdings wird dies mit einer
höheren bug-anfälligkeit erkauft. Seien Sie vorsichtig mit dem Umgang der
nicht kopierenden Prozeduren!)
Beschreibung der Prozeduren
Auf den Datentyp "List" können folgende Operationen ausgeführt werden:
CreateList()
------------
Erzeugt eine neue, leere Liste. Vor dieser Operation darf auf eine
Liste nicht zugegriffen werden.
AppendEntry()
-------------
Fügt einen Eintrag an das Ende der Liste an. Dabei werden die Daten
nicht kopiert, sondern nur ein Knoten mit einem Zeiger auf die Daten
an die Liste angehängt. Man muß hier aufpassen, daß man auf keinen Fall
lokale Variablen verwendet, oder den Speicher der Daten Dealloziert,
bevor man den Eintrag wieder aus der Liste entfernt hat. Man sollte die
Daten auch nicht (unbeabsichtigt) verändern bzw. deren Speicher wieder-
verwenden.
AppendEntryC()
--------------
Wie zuvor, kopiert jedoch die Daten in einen neu allozierten Speicher-
bereich. Somit dürfen hier auch lokale Variablen für den Paramenter "Data"
verwendet werden.
RemoveEntry()
-------------
Dies ist das Gegenstück zu AppendEntry() oder InsertEntry(). Es entfernt
einen Eintrag aus der Liste, ohne seinen Datenbereich zu deallozieren.
DeleteEntry()
-------------
Ist das Gegenstück zu AppendEntryC() oder InsertEntryC(). Es entfernt
einen Eintrag aus der Liste und aus dem Speicher.
DeleteList()
------------
Löscht eine komplette Liste mitsamt ihren Einträgen. Vorsicht: alle
noch vorhandenen Einträge werden dealloziert, was zu Problemen führen
kann, wenn Sie die nicht kopierenden AppendEntry()- oder InsertEntry()-
Prozeduren verwendet haben.
InsertEntry()
-------------
Fügt einen neuen Eintrag in eine Liste ein. Entgegen Exec.Insert()
wird vor der angegebenen Position eingefügt, d.h. wenn an der
Stelle des Eintrags 5 eingefügt wird, so wird der neue Eintrag
die neue Nr. 5, die alte Nr. 5 wird die neue Nr. 6 usw.
InsertEntryC()
--------------
Wie zuvor, Kopiert jedoch die Daten in einen neu allozierten Speicher-
bereich.
ReadEntry()
-----------
Gibt Adresse und Größe der Daten eines Eintrags zurück. Die Daten
werden nicht kopiert.
ReadEntryC()
------------
Wie zuvor, kopiert die Daten jedoch in einen VAR-Parameter.
ReplaceEntry()
--------------
Ersetzt das Datenfeld eines Eintrags durch ein neues. Hierbei wird
kein Speicher (de-)alloziert sondern nur die Zeiger umgestellt.
ReplaceEntryC()
---------------
Überschreibt ein Datenfeld eines Eintrags mit neuen Daten, d.h. kopiert
die Übergebenen Daten in den alten Speicherbereich.
ListOk()
--------
Gibt an, ob die Operationen seit dem letzten Aufruf von ListOk()
erfolgreich waren, oder ob kein Speicher mehr frei war oder sonst
ein Fehler aufgetreten ist. Im Definitionsmodul steht eine Liste
aller möglichen Fehlerursachen.
EntriesInList()
---------------
Gibt an, wieviele einträge eine Liste hat.
LocateEntryAbs()
----------------
Gibt einen EntryPtr auf einen Eintrag mit der angegebenen Nummer
zurück. Für den ersten und Letzten Eintrag existieren besondere
Prozeduren (siehe unten).
LocateEntryRel()
----------------
Positioniert auf den Eintrag, der sich um einen bestimmten Offset
vor (negativ) oder hinter (positiv) dem angegebenen Eintrag befindet.
Für den direkten Vorgänger oder Nachfolger existieren besondere
Prozeduren (siehe unten).
FirstEntry()
------------
Gibt einen EntryPtr auf den ersten Eintrag zurück (Vorsicht: die Liste
darf nicht leer sein).
LastEntry()
------------
Gibt einen EntryPtr auf den letzten Eintrag zurück (Vorsicht: die Liste
darf nicht leer sein).
Successor()
-----------
Positioniert auf den Nachfolger eines Eintrags (sofern vorhanden).
Predecessor()
-------------
Positioniert auf den Vorgänger eines Eintrags (sofern vorhanden).
ListAllocProc, ListDeallocProc
------------------------------
Mit diesen Prozedurvariablen können Prozeduren installiert werden, die
von Lists für das Allozieren/Deallozieren von Speicher verwendet werden.
Voreingestellt sind die aus TaskMemory.
Unterstützung von Strings
-------------------------
Die einzelnen Einträge einer Liste dürfen unterschiedliche Länge haben,
wodurch variable Strings unterstützt werden.
Darüberhinaus wird beim Kopieren eines kürzeren in ein längeres Datenfeld
automatisch ein Nullbyte angehängt. Umgekehrt werden überstehende Zeichen
abgetrennt.
Weitere generische Datentypen
[1] Amok#7:List
[2] Amok#7:Queue
[3] Amok#7:Stack
[4] Amok#7:AVL
[5] Amok#13:Rows